home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / comms_w / wrcmdl13.zip / RCMDDLL.DOC < prev    next >
Text File  |  1994-12-30  |  12KB  |  368 lines
  1.   Winsock RCMD.DLL                                   Version 1.3
  2.   Copyright 1994 Denicomp Systems
  3.   All rights reserved
  4.   
  5.   DESCRIPTION
  6.   -----------
  7.   
  8.   Winsock RCMD.DLL is a Microsoft Windows 3.1 Dynamic Link Library that
  9.   provides a Windows Sockets compatible function that allows you to execute
  10.   commands on a remote host and retreive the output of those commands for
  11.   processing by your program.
  12.  
  13.   Winsock RCMD.DLL is similar to the "rcmd" library function found on many
  14.   Unix systems.  The DLL includes the main WinsockRCmd function, plus a
  15.   functions receive data over the connection from the remote host executing
  16.   the command.
  17.   
  18.   The remote host must be a system running the rshd server process
  19.   (i.e. a Unix system).  You cannot execute a command on another PC,
  20.   for example.
  21.  
  22.   Winsock RCMD.DLL is designed to execute non-interactive remote commands.
  23.   If you need to execute an interactive command on the remote host, use a
  24.   utility like Telnet.
  25.   
  26.  
  27.   REQUIREMENTS
  28.   ------------
  29.  
  30.   Winsock RCMD.DLL requires a PC running Windows 3.1 or higher, a Windows
  31.   Sockets compatible TCP/IP stack, and any programming language that supports
  32.   calls to DLL functions, such as C or Visual Basic.
  33.  
  34.  
  35.   =============================================================================
  36.  
  37.   FUNCTION: WinsockRCmd
  38.  
  39.   Syntax:
  40.   -------
  41.  
  42.   C:
  43.   
  44.   int FAR PASCAL WinsockRCmd (Host, Port, LocalUser, RemoteUser,
  45.                          Command, ErrorMsg, ErrorMsgLen)
  46.   
  47.        LPSTR Host;
  48.        int Port;
  49.        LPSTR LocalUser;
  50.        LPSTR RemoteUser;
  51.        LPSTR Command;
  52.        LPSTR ErrorMsg;
  53.        int ErrorMsgLen;
  54.   
  55.  
  56.   Visual Basic:
  57.  
  58.   Declare Function WinsockRCmd Lib "RCMD.DLL"
  59.               (ByVal RHost As String,
  60.                ByVal RPort As Integer,
  61.                ByVal LocalUser As String,
  62.                ByVal RemoteUser As String,
  63.                ByVal Cmd As String,
  64.                ByVal ErrorMsg As String,
  65.                ByVal ErrLen As Integer) As Integer
  66.  
  67.  
  68.   Usage:
  69.   ------
  70.   
  71.   The WinsockRCmd function initiates a connection to the remote host
  72.   and executes the specified command if access is permitted.  You can
  73.   then use the RCmdRead function to receive the standard output and
  74.   standard error output of the command.
  75.   
  76.   Parameters:
  77.   -----------
  78.  
  79.   Host:        Specifies the name of a remote host that is listed in the 
  80.                "hosts" file.  You will receive an error if the host name
  81.                is not found.
  82.   
  83.   Port:        Specifies the port to use for the connection.  Normally, this
  84.                is the well-known port number of 514.  This must be the port
  85.                number of the rshd server on the remote host.  No other server
  86.                (such as rexecd) is supported at this time.
  87.   
  88.   LocalUser:   The user name of the user on the local host (the PC).  This can
  89.                be NULL or an empty string if you want Winsock RCMD.DLL to
  90.                determine the name.  The method it uses is described later.
  91.  
  92.                This name is sent as the local user to the rshd server on the
  93.                remote host.  In general, it should be the same as the
  94.                RemoteUser parameter.
  95.  
  96.   RemoteUser:  The user name to be used at the remote host.  This must be
  97.                a valid user name at the remote host.  It can be NULL or an
  98.                empty string if you want Winsock RCMD.DLL to detemrine the
  99.                name.  The method is uses it described later.
  100.   
  101.   Command:     The command to be executed at the remote host.
  102.   
  103.   ErrorMsg:    A pointer to an area that can be used to store an error
  104.                message from WinsockRCmd.  If an error occurs while connecting
  105.                to the remote host, WinsockRCmd will return a negative result
  106.                and will store an error message here.  You can then optionally
  107.                use the error message as diagnostic output in your program.
  108.  
  109.   ErrorMsgLen: The maximum length of the error message returned.  This is
  110.                the number of characters available in ErrorMsg.
  111.   
  112.  
  113.   Return Value:
  114.   -------------
  115.  
  116.   If WinsockRCmd sucessfully connects to the remote host and begins executing
  117.   the specified command, it will return an integer "handle" that must be used
  118.   by the RCmdRead, RCmdHandle, and RCmdClose functions.  This handle will always
  119.   be greater than or equal to zero.
  120.   
  121.   If WinsockRCmd is not successful, it will return a negative number.  If the
  122.   number is -1, an error internal to WinsockRCmd occurred and a message
  123.   describing the error will be stored in ErrorMsg.  If the number is not -1,
  124.   it is a Windows Sockets error code (but negative).  ErrorMsg will also
  125.   contain a message attempting to describe the error.
  126.   
  127.   Notes:
  128.   ------
  129.  
  130.   The error message returned in ErrorMsg may contain newline characters
  131.   (ASCII 10).  The message is suitable for display using the standard
  132.   Windows MessageBox function or the Visual Basic MsgBox command/function.
  133.  
  134.   Execution of interactive commands (commands requiring keyboard input) is
  135.   not supported.
  136.  
  137.   Unlike the Unix "rcmd" function, WinsockRCmd does not have the ability
  138.   to separate the standard output and the standard error output of the
  139.   remote command.  Output to the standard output and standard error will
  140.   be intermixed.
  141.   
  142.  
  143.   =============================================================================
  144.  
  145.   Syntax:
  146.   -------
  147.  
  148.   C:
  149.   
  150.   int FAR PASCAL RCmdRead (Handle, DataIn, DataLen)
  151.   
  152.        int Handle;
  153.        LPSTR DataIn;
  154.        int DataLen;
  155.  
  156.   Visual Basic:
  157.  
  158.   Declare Function RCmdRead Lib "RCMD.DLL"
  159.               (ByVal hRCmd As Integer,
  160.                ByVal RData As String,
  161.                ByVal RCount As Integer) As Integer
  162.  
  163.  
  164.   Usage:
  165.   ------
  166.   
  167.   The RCmdRead function reads the output of the command executed with
  168.   WinsockRCmd.  This allows you to capture the standard output and
  169.   standard error output of the command you executed.
  170.  
  171.   Parameters:
  172.   -----------
  173.  
  174.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  175.               function.
  176.  
  177.   DataIn:     A pointer to an area of memory to hold the data received.
  178.  
  179.   DataLen:    The maximum number of bytes to receive.
  180.  
  181.  
  182.   Return Value:
  183.   -------------
  184.  
  185.   If RCmdRead is sucessful, it returns the number of bytes read.  It will be
  186.   a number greater than zero.
  187.  
  188.   If RCmdRead returns zero, there is no more data to read.  The command has
  189.   ended and you should call RCmdClose to terminate the connection.
  190.  
  191.   If RCmdRead returns a negative number, an error has occurred.  The number
  192.   will be the Windows Sockets error number (but negative).  You should call
  193.   RCmdClose even if an error occurs to free all resources used by the
  194.   connection.
  195.  
  196.  
  197.   =============================================================================
  198.  
  199.   Syntax:
  200.   -------
  201.  
  202.   C:
  203.   
  204.   int FAR PASCAL RCmdClose (Handle)
  205.   
  206.        int Handle;
  207.  
  208.   Visual Basic:
  209.  
  210.   Declare Function RCmdClose Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
  211.  
  212.  
  213.   Usage:
  214.   ------
  215.   
  216.   The RCmdClose function closes the connection to the remote host and
  217.   frees all resources used by the connection.  You should call RCmdClose
  218.   for each successful use of the WinsockRCmd function.
  219.  
  220.  
  221.   Parameters:
  222.   -----------
  223.  
  224.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  225.               function.
  226.  
  227.  
  228.   Return Value:
  229.   ------------
  230.  
  231.   If RCmdClose is sucessful, it returns zero.  If it is unsuccessful, it
  232.   returns a negative number that is the Windows Sockets error number (but
  233.   negative).
  234.  
  235.  
  236.   =============================================================================
  237.  
  238.   Syntax:
  239.   -------
  240.  
  241.   C:
  242.   
  243.   int FAR PASCAL RCmdHandle (Handle)
  244.   
  245.        int Handle;
  246.  
  247.   Visual Basic:
  248.  
  249.   Declare Function RCmdHandle Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
  250.  
  251.  
  252.   Usage:
  253.   ------
  254.   
  255.   The RCmdHandle function returns the Windows Sockets handle for the
  256.   connection, which can be used to call any Windows Socket function.
  257.  
  258.  
  259.   Parameters:
  260.   -----------
  261.  
  262.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  263.               function.
  264.  
  265.  
  266.   Return Value:
  267.   -------------
  268.  
  269.   RCmdHandle returns a Windows Sockets handle.  If you call RCmdHandle on
  270.   a WinsockRCmd connection that is not opened, the return value is undefined.
  271.  
  272.  
  273.  ============================================================================
  274.  
  275.   DETERMINING THE USER NAME
  276.   -------------------------
  277.  
  278.   If you use a NULL value or empty string for the LocalUser or RemoteUser
  279.   parameters of the WinsockRCmd function, the user name is determined by
  280.   first looking in the file WIN.INI in the Windows directory.  If this file
  281.   contains a section named "[RCMD]" and contains an entry named "User" in that
  282.   section, the name specified there will be used as the user name.  For
  283.   example, WIN.INI would contain:
  284.  
  285.      [RCMD]
  286.      User=joe
  287.  
  288.   If this appeared in WIN.INI, the user name would be "joe" and WinsockRCmd
  289.   would use this name.
  290.  
  291.   If this section does not appear in WIN.INI, WinsockRCmd uses the Computer
  292.   Name specified in the Windows for Workgroups Network Setup (found on the
  293.   Control Panel).  This name is converted to lowercase characters and
  294.   WinsockRCmd uses this name.  Therefore, if no user name is specified in
  295.   WIN.INI, the Computer Name of the PC must be set up as a valid user on the
  296.   remote host, in addition to being included in the remote host's
  297.   /etc/hosts.equiv file.
  298.  
  299.   (If you are not using Windows for Workgroups and your network does not
  300.   provide the services that Windows for Workgroups provides, you must use
  301.   WIN.INI to specify the user name.)
  302.  
  303.  
  304.   SECURITY
  305.   --------
  306.   
  307.   The remote host allows access only if at least one of the following
  308.   conditions is satisfied:
  309.   
  310.   * The name of the local host is listed as an equivalent host in the
  311.     /etc/hosts.equiv file on the remote host.
  312.  
  313.     The method of specifying the local host name is determined by the
  314.     particular TCP/IP stack you are using.
  315.   
  316.   * If the local host is not in the /etc/hosts.equiv file, the user's home
  317.     directory on the remote host must contain a .rhosts file that lists the
  318.     local host and user name.
  319.   
  320.   * The user's login on the remote host does not require a password.
  321.  
  322.   The .rhosts file in the user's home directory must be owned by either
  323.   the user specified or root, and only the owner should have read and write
  324.   access.
  325.   
  326.   EXAMPLE
  327.   -------
  328.  
  329.   For a complete example of the use of WinsockRCmd in C, see the CRSH
  330.   program provided in the distribution.
  331.  
  332.   For a example of the use of WinsockRCmd in Visual Basic, see the VRSH
  333.   program provided in the distribution.  This is actually the source code
  334.   of the Visual RSH program provided with the Winsock RCP and RSH package.
  335.  
  336.  
  337.   // Assumes that the host is in "rhost", the user is in "ruser", and the
  338.   // command is in "cmd".
  339.  
  340.      int hRCmd;
  341.      char c;
  342.  
  343.      hRCmd = WinsockRCmd(rhost,514,ruser,ruser,cmd,errmsg,sizeof(errmsg));
  344.  
  345.      if (hRCmd < 0)
  346.        MessageBox(NULL,errmsg,"Remote Shell",MB_OK);
  347.      else
  348.      {
  349.     while(RCmdRead(hRCmd,&c,1) > 0)
  350.           DisplayChar(c);
  351.      }
  352.  
  353.      RCmdClose(hRCmd);
  354.  
  355.  
  356. SUPPORT
  357. -------
  358.  
  359. Support is available via U.S. Mail and Compuserve/Internet:
  360.  
  361. Denicomp Systems
  362. P.O. Box 731
  363. Exton, PA  19341
  364.  
  365. Compuserve:  71612,2333
  366. Internet:    71612.2333@compuserve.com
  367.  
  368.